########################
MacPerl Support in Alpha
########################

Introduction
============

This document describes the use of the MacPerl menu in Alpha.  The 
MacPerl menu was written to allow Alpha to act as a front end for 
Matthias Neeracher's standalone MacPerl application and to make it 
possible to "attach" Perl scripts to Alpha.  It provides a number of 
features designed to make the use and development of Perl scripts on the 
Mac more convenient.  These are detailed in the rest of this document 
(most easily navigated using the "{}" menu on the sidebar), but here's a 
quick overview:

Editing Perl scripts...

 Perl keywords and special variables are colorized in Perl mode.

 The Perl 4 man page is provided as an on-line reference, 
  available as the file "Perl Commands" in Alpha's Help menu; it has 
  been colorized and indexed to make it easy to read and navigate.

 The man page can be referenced by command-double-clicking a 
  highlighted Perl keyword or special variable in your Perl script.
  
 Source files mentioned in require statements can be opened by 
  command-double-clicking as well. 
 
Running Perl Scripts...

 MacPerl scripts can be run directly from Alpha - a script can be 
  a text window in Alpha, a highlighted selection from a window, or a 
  disk file.

 You can save scripts as MacPerl droplets and runtime applications 
  directly from Alpha.

 Perl scripts that read from standard input and write to standard 
  output may be used to process text in Alpha's text windows.

Debugging Perl scripts...

 When a script fails, the error messages are displayed and the 
  script is brought up with the line that caused the error highlighted.

 A flag can be set to cause scripts to run under the Perl 
  debugger (without modifying the script).


Currently, no explicit support or documentation is provided for Perl 5, 
but this will follow once a stable port of Perl 5 to the 68k Macintosh 
emerges.

Instructions for obtaining the MacPerl application are given further below.


Installation
============

No special installation procedure is required before using this package.  
However, there are a couple of things that you may need to do to 
configure things for your particular machine.

MacPerl application and library
-------------------------------

Alpha needs to know where to find your MacPerl application in order to 
interact with it, and will automatically prompt you to locate it if it 
doesn't know where it is.  You can always check and/or change the path 
that Alpha uses by selecting the "MacPerl" entry in the "Mode:App Paths" 
menu.

When opening "require"d source files via the command-double-click 
mechanism, Alpha will always look in the "lib" folder in the MacPerl 
application directory.  To have Alpha look for library files elsewhere, 
you can specify an additional personal library folder, using the 
"MacPerl lib folder" entry in "Mode:App Paths" menu.

Text Filters Setup
------------------

If you want to use Perl scripts to process Alpha text buffers (see 
Text Filters), you'll need to arrange that the Perl menu is visible 
while you're in Text mode.  While in Text mode, select "Set Mode 
Menus" from the "" pop-up menu on the side-bar and command-click 
on "perlMenu" in the list of menus shown.  The little camel icon 
should appear on the menu bar when you're done.

The MacPerl menu contains a hierarchical submenu of preattached scripts 
to be used as text filters.  A sample collection of such scripts is 
distributed with Alpha in the ":Tcl:UserCode:Text Filters:" folder.  You 
can specify your own folder of scripts using "MacPerl Text Filters 
folder" entry in "Mode:App Paths" menu.

Option flags

There are a handful of flags you can set to modify the way Alpha and 
MacPerl interact while running Perl scripts.  These can be set from 
either the MacPerl menu or the "" pop-up menu on the side-bar.  They're
described in detail below.


Perl Mode
=========

Perl mode is entered automatically whenever you open a file with a ".pl" 
or ".ph" suffix; you can also invoke it explicitly using the modes menu 
(downward triangle) on the sidebar.  Perl mode offers a number of 
features supporting the editting and debugging of Perl scripts:

Basic language support
----------------------

 Perl keywords and special variables appear in blue in Perl mode.

 A single line or a selected block of lines may be commented out by 
  using the "Comment Line" command under the "Convert" menu.  Lines
  are uncommented using "Uncomment Line", which appears in the "Convert" 
  menu when the option key is held down.

 Alpha will create an index of all subroutines in your Perl script when 
  you select "Mark File" from the Marks menu on the sidebar (the "{}" 
  button).  Once created this index is saved with your file.  

  When you open a Perl script that hasn't already been indexed, an index 
  is automatically created.

Command-double-clicking
-----------------------

A simple form of hypertext help is invoked by double-clicking on 
certain pieces of text while the command key is held down: 

 The online man page can be referenced by command-double-clicking a 
  highlighted Perl keyword or special variable in your Perl script.
  
  Most of the clickable keywords and variables will be colored blue.
  Special variables containing alphabetic characters, .e.g. @ARGV,
  are also clickable but are not colored. 
  
 Command-double-clicking on the name of the source file in a require
  statement will cause that file to be opened by Alpha.  

  Alpha will look for the file in the current script's folder, in your local 
  library folder and in the MacPerl lib folder (in that order).  The local 
  lib folder may be specified interactively by the user (see Installation).
 


MacPerl Menu
============

Alpha's MacPerl menu allows a number of actions.  These are ...

MacPerl interaction
-------------------

Macperl  				Switch to the MacPerl application.

Tell Macperl... >
	
	Open In Macperl		Open the current document in MacPerl.
	
	Save As Droplet		Save the current document as a MacPerl droplet.
	
	Save As Droplet		Save the current document as a MacPerl runtime script.
	
	Save As CGI			Save the current document as a MacPerl CGI applet.
	
			    A bug in the AEGizmos package makes it impossible to create 
			    CGI applets directly from Alpha at this point.  You will have 
			    to open the script in MacPerl and save it from there.
	
	Open Output Window 	Retrieve the contents of MacPerl's main output window 
	    				into a new window under Alpha.
	
	Close Output Window	Close MacPerl's main output and debugger windows.
	
	Quit  				Force the MacPerl application to quit. 

Running Perl Scripts
--------------------

Run The Selection  	Execute the selected text as a Perl script.

Run The Buffer  	Execute the current text window as a Perl script.

Save And Run  		Save the current window and run the saved file as 
					a Perl script. (see Current Directory)

Run A File  		Run a selected disk file as a Perl script.  

Applying Text Filter Scripts
----------------------------

Text Filters >	A hierarchical menu of "preattached" scripts to use 
				as text filters.  When a script is selected from this menu, 
				it is immediately applied to the current text window.
				
				The menu is built from the contents of a user-selected 
				folder.  The folder is chosen using the "Mode:App Paths" 
				menu command on the main menubar or the "Text Filters Folder"
				command under the Macperl "Filter Options" submenu (below).
				
Select Buffer As Filter	Select one of the open text windows to use as the 
						text filter script.

Select File As Filter	Select a file to use as the text filter script.

Repeat Last Filter		Run again the last filter that was used.

						If the contents of the file or buffer has changed, the
						new script is run.


Option flags
------------
	
General Options >	Flags that control Alpha's behavior when executing 
					ordinary scripts (not text filters).
 	
 	Retrieve Output		Automatically retrieve any output written to the 
 						MacPerl output window and display it in a new 
 						window under Alpha. (same as "perlGetOutput")
 						
 						If the mode variable "perlRecycleOutput" is set, 
 						the previous output window is overwritten.
 						
 	Auto Switch			Switch to MacPerl while scripts are being executed.
 						Otherwise, Alpha remains frontmost until the script
 						finishes. (same as "perlAutoSwitch")

 	Prompt For Args		Have Alpha prompt you for command-line arguments 
 	                    to be passed to the script. (same as "perlPromptArgs")

	Use Debugger 		Force the script to run under the MacPerl debugger.  
						(same as "perlUseDebug")
 	
 	                    Control is automatically switched to MacPerl
 	                    when the debugger is used.
	
Filter Options >		Flags controlling the behavior of text filters mechanism.
 					
 	Apply To Buffer		Apply the filter to the entire current text window;
 						otherwise, only the selected text is used.
						(same as "perlUseBuffer")
 						
 	Overwrite Selection	When checked, the output from the text filter 
 						script will replace the input text in the original
 						window.  Otherwise, the output is written into
 						a new window.
						(same as "perlOverwrite")

    Text Filters Folder  Select the folder from which the Text Filters menu is 
					    built.  (You can also use the "Mode:App Paths" menu.)

    Rebuild Filter Menu  Reconstruct the "Text Filters" menu from the 
    					contents of the designated "Text Filters" folder.
    	
    					
Mode variables
--------------

A more complete set of Perl option flags are also settable through the 
flags menu "" on the sidebar (while you're in Perl mode).

perlAutoSwitch 		(same as "Auto Switch" under "General Options")
perlGetOutput		(same as "Retrieve Output" under "General Options")
perlOverwrite		(same as "Overwrite Selection" under "Filter Options")
perlPromptArgs 		(same as "Prompt For Args" under "General Options")
perlUseDebug 		(same as "Use Debugger" under "General Options" ) 
perlUsebuffer 		(same as "Apply To Buffer" under "Filter Options")

perlRecycleOutput 	If selected, output returned by Macperl overwrites 
					previous output in the "* Perl Output *" window in Alpha,
					instead of going into a new window.

There are also two mode variables that may be examined

perlLastFilter		Contains the location of the last text-filter script used.

perlCmdlineArgs 	Contains the last command-line options supplied.

					Note these are only passed to scripts when the "Prompt for  
					Args" option is active.


Running Scripts
===============

Running scripts using the MacPerl menu is pretty straightforward.  You 
can send the current selection, the entire current buffer, or a disk 
file to MacPerl for execution as a Perl script; the result will be the 
same as if you ran the script from MacPerl itself.  Here are listed some 
important points to remember when running Perl scripts using the MacPerl 
menu.  

Input and Output
----------------

	Except for text filter scripts, the standard input for your script 
	is taken from the keyboard (while MacPerl is in the foreground)
	and standard output goes to MacPerl's output window.
	
	If you need to interact with the script while it's running, make 
	sure that you've selected the "AutoSwitch" flag under "General 
	Options".

	To get the output from your script, select the "Retrieve Output" 
	flag under "General Options", this will cause Alpha to copy any 
	output to Macperl's standard output window back into Alpha after 
	your script has completed.  You can always do this manually by 
	using the "Get Output Window" command under the "Tell Macperl" 
	submenu.
	
	Again, if you need to see the results while the script is running, 
	use "AutoSwitch" to bring MacPerl to the foreground during script 
	execution.

Current Directory
-----------------

For the purpose of resolving relative file references, etc., within your 
script, it's important to understand how the current directory of the 
running script (as returned by `pwd` ) is determined.

	If you run a script file (using "Run A File"), then the folder 
	containing that file is the current folder.

	If you run a script from a text buffer (using "Run The Buffer" or "Run 
	The Selection") , it is as though you ran it directly from a window in 
	the MacPerl application, and so the current directory your script sees 
	is the MacPerl application folder.
	
	If you run a script from a buffer using the "Save and Run" command, 
	then the script is first saved to disk and then executed as a script 
	file.  In this case, the current directory is that of the script file.


Command-line Args
-----------------

 If the menu flag "Prompt For Args" is checked, then the user is prompted 
  for command-line arguments at the time the script is run.  These will be 
  available inside the script through the @ARGV array, as usual.  They are 
  also saved in the Perl-mode variable "perlCmdlineArgs", and become the 
  default arguments the next time the script is executed.

Error Messages
--------------

 If the script fails for some reason, Alpha will read the error messages 
  returned by MacPerl and write them back into a new text window, called 
  "* Perl Errors *".  

 The script that generated the error is brought up 
  and the first line specifically referenced in an error message is 
  highlighted.

  Note that error-trapping remains active whether "Retrieve Output" is set 
  or not.

Interrupting a Script
---------------------

When you run a Perl script from Alpha, Alpha will display the watch 
cursor and wait for the reply from Macperl before doing anything else.  
There may be times when this is inappropriate, for instance, if you 
expect the script to run for a long time or if you think the script is
misbehaving for some reason.

 You can always tell Alpha to stop waiting for a script to finish by 
  hitting "Cmd-.".  
  
  This does not abort the script itself; to do that you'll have to switch 
  over to MacPerl to terminate the script there, as well.

 When you interrupt a script in this way, Alpha will no longer 
  automatically get the output or error messages from MacPerl, when and if 
  the script does finally terminate.
  
  You can always retrieve the contents of the output window yourself using 
  "Get Output Window" from the "Tell MacPerl" submenu or simply by 
  switching over to Macperl itself.

There are some simple causes for a hung script.  For instance, if 
MacPerl is configured to check for "#!" lines in scripts and yours 
doesn't have one, it will put up a dialog asking whether or not to 
procede.  If you didn't switch over to MacPerl when the script was run, 
you have know way of knowing this, and so you and Alpha may end up just 
sitting there waiting.


Text Filters
============

Perl is, among other things, a powerful tool for extracting and 
rewriting data from text files.  On a Unix system, one would 
typically write text-processing scripts to read from "standard 
input" and write to "standard output", taking advantage of 
command-line i/o redirection to specify the actual input and output 
files used at any given time.  On the Mac, the typical absence of a 
command-line interface makes it harder to use this elegant method.

The MacPerl menu in Alpha makes it possible to use scripts that 
read from standard input and write to standard output to process 
text buffers in Alpha directly.  Any text window can be used as 
standard input and standard output can either be directed back to 
that same window or to a newly created one.  The script used may 
either be a disk file or yet another Alpha text window. 

Applying a Text Filter 
----------------------

The procedure for using Perl text filters in Alpha is simple:

1.  Bring the text window you want to operate on to the front and select 
	(highlight) the text that will be the input to the script.
   
   * If the "Apply To Buffer" option is selected, then the entire text 
     window will be used as input and any text selection is ignored.
   
   * Only complete lines are used as input.  The text used will be extended 
	 to include all of the lines on which the selected text lies.

2.	Select a Perl script using one of the commands, "Select Buffer As 
	Filter", "Select File As Filter" or "Repeat Last Filter" from the Perl 
	menu, or by choosing one of the scripts listed in the "Text Filters" 
	submenu.

   * You can see the name of the last script used by examining the 
     variable "perlLastFilter" under the "" menu in Perl mode. This
     is the script that will be used if you use "Repeat Last Filter" 
     
   * If the "Prompt For Args" option has been selected, you'll be given 
     a dialog box to type in the command-line arguments for the script. 

3.  The output of the script is written back out, either in the place of 
	the input text (if the "Overwrite Selection" option is selected) or into 
	a new text window.
		
	* As always, Alpha's unlimited undo capability let's you recover if you 
	  accidently overwrite the input text when you didn't want to.
	
	* If the script halts on an error, the filter operation is aborted 
	  and any error messages are displayed in a new window.


The ability to take the script itself from a text window allows simple 
one-time scripts to be created and applied on the fly.  This can be very 
useful because, even with the overhead to start up MacPerl, large-scale 
global search-and-replace operations (hundreds of replaces) can be 
substantially faster in MacPerl than in Alpha.  Also, you might find 
it easier to apply a series of regular expression substitutions using a 
single, short Perl script, rather than a number of separate "Find" and 
"Replace All" commands in Alpha.


Preattached Scripts
-------------------

Frequently used text filter scripts can be conveniently accessed by 
placing them in a folder called "Text Filters" within the MacPerl 
application folder.  When the MacPerl menu is first created, it looks in 
this folder and builds a hierarchical submenu from the names of the 
scripts that it finds.  Note that it will also create a "Text Filters" 
folder if one doesn't already exist.

A sampling of useful :-) Perl scripts is distributed with Alpha in 
the folder ":Tcl:UserCode:Text Filters".  

Of the scripts in the sample collection, the "Text Munging" scripts 
("shuffle", "sort lines", "travesty", and "wordcount") were taken from 
the Camel book (Programming Perl).  The "s2p" script is my adaptation 
of the standard code that converts Unix "sed" scripts to Perl (it was 
modified to work without using the C preprocessor.) "Strip Mail Headers" 
takes e-mail files and edits out any header lines but the few that I 
typically care about ("From:, "Date:", etc..).  "CC To BibTeX" is a 
script I use that takes listings from the online "Current Contents" 
database and rewrites them as BibTeX database entries.  To try it out, 
select (highlight) the sample Current Contents citation below and choose 
"CC To BibTeX" from the "Text Filters" submenu (make sure that "Apply 
To Buffer" is _not_ checked before you do!)

288. VOS MH; LAMBRY JC; ROBLES SJ; YOUVAN DC; and others.
       FEMTOSECOND SPECTRAL EVOLUTION OF THE EXCITED STATE OF BACTERIAL
     REACTION CENTERS AT 10-K.
       PROCEEDINGS OF THE NATIONAL ACADEMY OF SCIENCES OF THE UNITED STATES OF
     AMERICA, 1992 JAN 15, V89 N2:613-617.


Bugs, etc.
==========

Comments and suggestions regarding this package are always welcome.  If 
there's something that bothers you, or some additional capability that 
you'd like to see, let me know and I'll see what I can do.

Bug reports and any other comments should be directed to

     Tom Pollard <pollard@chem.columbia.edu>


Version History
===============

2.3  7/95  -  Minor tweaks and code rearrangement.
2.2  6/95  -  Text filters act only on current line if "Apply to Buffer" is
                 false and no text has been selected.
              More verbose commentary when running scripts.
              Bug fix in error-marking for scripts sent as AppleEvent parameters.
              Cmd-dbl-clicking a function call jumps to function, if
                 defined in the same file.
2.1  6/95  -  Cmd-dbl-clicking a 'require'd filename opens the file.
2.0  6/95  -  Minor bug fixes (incl. keyword decapitalization), and
              Alpha 6.0b17 compatibility updates.
              Text Filters folder is settable from the App Paths menu now.
1.9  5/95  -  Cmd-dbl-clicking Perl keywords and special variables displays
                 the man page info.
1.8  4/95  -  Menu reorganized somewhat.
              Text Filters folder can now be anywhere.
              "ApplyToBuffer" flag ignored if text has been selected.
1.7  1/95  -  Updated to take advantage of MacPerl 4.1.4 AppleEvent features:
               1) Text filters use 'batch' doScript (.: STDOUT file obsolete)
               2) Filter scripts sent as doScript params (.: SCRIPT file obsolete)
               3) "Save As Droplet" and "Save as Runtime" commands added.
              Errors generated in 'require'd files are now displayed correctly
1.6 10/94  -  "UseDebugger" flag added (forces scripts to run under debugger).
              Key bindings added for some menu commands.
              "perlDoScript{,2,3}" procs consolidated into a single proc.
              "saveAndRun" option added.
              Command-line args now parsed into units more correctly, in
                  particular, quoted file names aren't broken up.
              "Close Output Window" added to "Tell MacPerl" menu.
              Updated for Alpha 5.98 to load when menu is inserted.
              The error messages window is now recycled.
              "perlRecycleOutput" recycles output window.
              Minor bug fixes.
1.5  9/94  -  MacPerl menu rearranged somewhat.
              Explicit "Get Output Window" command added to menu.
              Reading "#!" line for args is incompatible w/ standard,
                  so it's been dropped.
              Only scan the first 40 output lines for error messages (faster)
              "wrapFilterScript" no longer opens STDIN
              Text filters may now use command-line args
              STDIN for text filters passed as explicit cmd-line arg 
1.4  9/94  -  The "#!" line of every script is read for command-line args.
              "PromptForArgs" menu flag added.
              "perlCmdlineArgs" modeVar holds default command-line args.
              Scripts are sent using custom "perlDoScript2" proc.
1.3  9/94  -  When any script generates a compilation error, the file 
                  containing the script is brought up with the offending 
                  line highlighted; all error output is also written to
                  a "Perl Error Messages" window.
              'repeatLastFilter' runs again the last text-filter script used.
              'perlLastFilter' modeVar holds pathname of last filter.
              Menu flags now mirrored as modeVars, so they can be saved and
                  restored between sessions.
              Minor bug fixes.
1.2  8/94  -  'retrieveOutput' and 'autoSwitch' flags added.
              'openInMacperl' added.
              MacPerl output window now closed before new scripts are sent.
              Filters now abort if there are compilation errors, and
                   MacPerl diagnostic output retrieved and displayed.
1.1  8/94  -  'quitMacperl' added.
              perl-mode file-marking updated for Alpha 5.90
              Simplified installation via 'loadMacperl'(Pete Keleher).
1.0  7/94  -  perl-mode setup updated for Alpha 5.85:
                   keyword colorization supported
                   custom file-marking added
              #! lines in filter scripts now handled correctly
              Workarounds installed for AppleEvent problem in MacPerl 4.1.3
0.9  3/94  -  perl-mode stuff added, and
              highlighted 'Perl commands' file (man page) prepared
              minor bug fixes, too
0.8  3/94  -  flags are now check-marked
0.7  3/94  -  nested Text Filters folder now supported
              menu format modified somewhat
0.6  3/94  -  'applyToBuffer' flag added
              scripts in Alpha buffers can now be used as filters
0.5  2/94  -  'filters', 'open special' submenu added
              'overwrite' flag added
0.2  1/94  -  menu support added by Martijn Koster <m.koster@nexor.co.uk>
              'execute selection', 'execute buffer' commands added
0.1  9/93  -  text filter functionality created


MacPerl application
===================

MacPerl was written (ported to the Mac) by

          Matthias Neeracher <neeri@iis.ee.ethz.ch>, and 
          Tim Endres <time@ice.com>.

If you don't already have MacPerl, it's available by anonymous ftp 

  ftp://ftp.switch.ch/software/mac/perl ,  or
  ftp://ftp.share.com/pub/macperl
  

More information about MacPerl is available from the MacPerl Q&A page,

  http://err.ethz.ch/members/neeri/macintosh/perl-qa.html ,
  
Hal Wine's official MacPerl FAQ,

  ftp://ftp.netcom.com/pub/ha/hal/MacPerl/
  
and Sandra Silcott's MacPerl Primer, 

  http://www.unimelb.edu.au/~ssilcot/macperl-primer/home.html
  
which contains useful hints and sample scripts.
       
---------------------------------------------------------------------------
